Beef up docs about integrating Cargo with other stuff

diff --git a/src/doc/external-tools.md b/src/doc/external-tools.md
new file mode 100644 (file)
index 0000000..bf07e7f
--- /dev/null
+++ b/src/doc/external-tools.md
@@ -0,0 +1,103 @@
+% External tools
+
+One of the goals of Cargo is simple integration with third-party tools, like
+IDEs and other build systems. To make integration easier, Cargo has several
+facilities:
+
+* `cargo metadata` command, which outputs project structure and dependencies
+  information in JSON,
+
+* `--message-format` flag, which outputs information about a particular build,
+
+* support for custom subcommands.
+
+
+# Information about project structure
+
+
+You can use `cargo metadata` command to get information about project structure
+and dependencies. The output of the command looks like this:
+
+```text
+{
+  // Integer version number of the format.
+  "version": integer,
+
+  // List of packages for this workspace, including dependencies.
+  "packages": [
+    {
+      // Opaque package identifier.
+      "id": PackageId,
+
+      "name": string,
+
+      "version": string,
+
+      "source": SourceId,
+
+      // A list of declared dependencies, see `resolve` field for actual dependencies.
+      "dependencies": [ Dependency ],
+
+      "targets: [ Target ],
+
+      // Path to Cargo.toml
+      "manifest_path": string,
+    }
+  ],
+
+  "workspace_members": [ PackageId ],
+
+  // Dependencies graph.
+  "resolve": {
+     "nodes": [
+       {
+         "id": PackageId,
+         "dependencies": [ PackageId ]
+       }
+     ]
+  }
+}
+```
+
+The format is stable and versioned. When calling `cargo metadata`, you should
+pass `--format-version` flag explicitly to avoid forward incompatibility
+hazard.
+
+If you are using Rust, there is [cargo_metadata] crate.
+
+[cargo_metadata]: https://crates.io/crates/cargo_metadata
+
+
+# Information about build
+
+When passing `--message=format=json`, Cargo will output the following
+information during the build:
+
+* compiler errors and warnings,
+
+* produced artifacts,
+
+* results of the build scripts (for example, native dependencies).
+
+The output goes to stdout in the JSON object per line format. The `reason` field
+distinguishes different kinds of messages.
+
+Information about dependencies in the Makefile-compatible format is stored in
+the `.d` files alongside the artifacts.
+
+
+# Custom subcommands.
+
+Cargo is designed to be extensible with new subcommands without having to modify
+Cargo itself. This is achieved by translating a cargo invocation of the form
+cargo `(?<command>[^ ]+)` into an invocation of an external tool
+`cargo-${command} that then needs to be present in one of the user's `$PATH`
+directories.
+
+Custom subcommand may use `CARGO` environment variable to call back to
+Cargo. Alternatively, it can link to `cargo` crate as a library, but this
+approach has drawbacks:
+
+* Cargo as a library is unstable, API changes without deprecation,
+
+* versions of Cargo library and Cargo binary may be different.

diff --git a/src/doc/header.html b/src/doc/header.html
index 8d12def3165ee2dd9af35002d5c4a69f32cf8748..f10cf935f470ec861f5268cf1eadc3240934df3c 100644 (file)
--- a/src/doc/header.html
+++ b/src/doc/header.html
@@ -40,7 +40,7 @@
                 <li><a href='pkgid-spec.html'>Package ID specs</a></li>
                 <li><a href='environment-variables.html'>Environment Variables</a></li>
                 <li><a href='source-replacement.html'>Source Replacement</a></li>
-                <li><a href='machine-readable-output.html'>Machine readable output</a></li>
+                <li><a href='external-tools.html'>External Tools</a></li>
                 <li><a href='policies.html'>Policies</a></li>
             </ul>
         </div>

diff --git a/src/doc/machine-readable-output.md b/src/doc/machine-readable-output.md
deleted file mode 100644 (file)
index 7b0463a..0000000
--- a/src/doc/machine-readable-output.md
+++ /dev/null
@@ -1,78 +0,0 @@
-% Machine readable output.
-
-Cargo can output information about project and build in JSON format.
-
-# Information about project structure
-
-You can use `cargo metadata` command to get information about project structure
-and dependencies. The output of the command looks like this:
-
-```text
-{
-  // Integer version number of the format.
-  "version": integer,
-
-  // List of packages for this workspace, including dependencies.
-  "packages": [
-    {
-      // Opaque package identifier.
-      "id": PackageId,
-
-      "name": string,
-
-      "version": string,
-
-      "source": SourceId,
-
-      // A list of declared dependencies, see `resolve` field for actual dependencies.
-      "dependencies": [ Dependency ],
-
-      "targets: [ Target ],
-
-      // Path to Cargo.toml
-      "manifest_path": string,
-    }
-  ],
-
-  "workspace_members": [ PackageId ],
-
-  // Dependencies graph.
-  "resolve": {
-     "nodes": [
-       {
-         "id": PackageId,
-         "dependencies": [ PackageId ]
-       }
-     ]
-  }
-}
-```
-
-
-# Compiler errors
-
-If you supply `--message-format json` to commands like `cargo build`, Cargo
-reports compilation errors and warnings in JSON format. Messages go to the
-standard output. Each message occupies exactly one line and does not contain
-internal `\n` symbols, so it is possible to process messages one by one
-without waiting for the whole build to finish.
-
-The message format looks like this:
-
-```text
-{
-  // Type of the message.
-  "reason": "compiler-message",
-
-  // Unique opaque identifier of compiled package.
-  "package_id": PackageId,
-
-  // Unique specification of a particular target within the package.
-  "target": Target,
-
-  // The error message from the compiler in JSON format.
-  "message": {...}
-}
-```
-
-Package and target specification are the same that `cargo metadata` uses.